<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
  <link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css" />
  <title>Preferences</title>
</head>

<body>

<h2>Code Coverage Preferences</h2>

<p>
  The behavior of the EclEmma plug-in can be adjusted in the Eclipse
  <i>Preferences</i> dialog. Open the dialog from the
  <i>Window</i> &rarr; <i>Preferences</i> menu. EclEmma's settings are located
  on the page <i>Java</i> &rarr; <i>Code Coverage</i>. Or simply type
  <i>coverage</i> in the filter field. The <i>Code Coverage</i> preferences page
  contains the following options.
</p>

<ul>
  <li><b>Open coverage view automatically:</b>
    Whenever a new coverage session becomes active the
    <a href="coverageview.html"><i>Coverage</i> view</a> can be automatically shown
    in the current workbench window. (Default: on)
  </li>
  <li><b>Activate new coverage sessions:</b>
    A new session is created when a <a href="launching.html">coverage launch</a>
    terminates or a session is <a href="importexport.html">imported</a>. This
    option determines whether the new session should become automatically active,
    i.e. its result data is shown in the coverage view and in the Java editors.
    (Default: on)
  </li>
  <li><b>Remove coverage sessions for removed launches:</b>
    Coverage session will be available until they are manually deleted in the
    <a href="coverageview.html"><i>Coverage</i> view</a>. For frequent test runs
    it might be more convenient to remove them automatically with the associated
    launches. (Default: off)
  </li>
  <li><b>Reset execution data on dump:</b>
    For a running application coverage data can be dumped at any time from
    <a href="coverageview.html"><i>Coverage</i> view</a>. This option determines
    whether execution data is reset after such an intermediate dump.
    (Default: off)
  </li>
</ul>

<p>
  When a launch configuration is executed in code coverage mode the first time
  EclEmma selects class path entries that will be in scope for code coverage
  analysis by default. There are several options to modify the default selection
  behavior:
</p>

<ul>
  <li><b>Source folders only:</b>
    Consider source based class path entries only. (Default: on)
  </li>
  <li><b>Same project only:</b>
    Pick only class path entries from the same project. This option works only for
    launch configurations that have a project associated, i.e. Java applications.
    (Default: off)
  </li>
  <li><b>Only path entries matching:</b>
    Comma separated list of strings that must match with the class path entry.
    A class path entry matches the filter, if it contains one of the given
    strings. (e.g. "src/main/java", Default: no filter)
  </li>
</ul>

<p>
  <b>Warning:</b> If your settings do not match any of the class path entries in
  your project(s), every new launch in coverage mode will have an empty analysis
  scope.
</p>

<p>
  For technical reasons it might be necessary to exclude certain classes from
  code coverage analysis. The following options configure the coverage agent to
  exclude certain classes from analysis. Except for performance optimization or
  technical corner cases these options are normally not required.
</p>

<ul>
  <li><b>Includes:</b>
    A list of class names that should be included in execution analysis. The
    list entries are separated by a colon (:) and may use wildcard characters
    (* and ?). (Default: *)
  </li>
  <li><b>Excludes:</b>
    A list of class names that should be excluded from execution analysis. The
    list entries are separated by a colon (:) and may use wildcard characters
    (* and ?). (Default: <i>empty</i>)
  </li>
  <li><b>Exclude classloaders:</b>
    A list of class loader names that should be excluded from execution
    analysis. The list entries are separated by a colon (:) and may use wildcard
    characters (* and ?). This option might be required in case of special
    frameworks that conflict with JaCoCo code instrumentation, in particular
    class loaders that do not have access to the Java runtime classes.
    (Default: sun.reflect.DelegatingClassLoader)
  </li>
</ul>

<p>
  <b>Warning:</b> Use these options with caution! Invalid entries might break
  the code coverage launcher. Also do not use these options to define the scope
  of your analysis. Excluded classes will still show as not covered.
</p>


<h3>Other Relevant Preference Pages</h3>

<p>
  Java elements in the various Eclipse views like the <i>Package Explorer</i>
  might be directly <a href="decorators.html">decorated</a> with coverage data
  from the current session. This can be enabled on the page <i>General</i> &rarr;
  <i>Appearance</i> &rarr; <i>Label Decorators</i>. The corresponding entry is
</p>

<ul>
  <li><b>Java Code Coverage</b> (Default: off)</li>
</ul>

<p>
  The <a href="annotations.html">annotation</a> style for code coverage in
  editors can be adjusted on the page <i>General</i> &rarr; <i>Editors</i> &rarr;
  <i>Text Editors</i> &rarr; <i>Annotations</i>. The corresponding entries are:
</p>

<ul>
  <li><b>Full Coverage</b> (Default: green highlighting)</li>
  <li><b>Partial Coverage</b> (Default: yellow highlighting)</li>
  <li><b>No Coverage</b> (Default: red highlighting)</li>
</ul>

</body>
</html>
